# Configuration

Languine uses a JSON configuration file (languine.json) to manage your translation setup. This file defines your source and target languages, as well as the files that need to be translated.

---

## Basic Configuration

Here's a basic example in both formats:

```json title="languine.json"
{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "files": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}
```

Let's break down the different sections in the configuration file.

---

## Locale Configuration

The locale section defines your translation languages:

- source: Your primary language for content creation (e.g., "en" for English)
- targets: An array of languages you want to translate into (e.g., ["es", "fr", "de"] for Spanish, French, and German)

Languine supports a wide range of language codes, including:
- Simple codes: en, es, fr, de
- Region-specific codes: pt-BR, zh-CN, zh-TW

## File Configuration

The files section defines which files Languine should translate. You can configure multiple file types and patterns:

---

### JSON Files
```json
files: {
  json: {
    include: ["locales/[locale].json"],
  },
}
```

---

### Markdown/MDX Files
```json
files: {
  md: {
    include: ["docs/[locale]/*.md"],
  },
  mdx: {
    include: ["blog/[locale]/*.mdx"],
  },
}
```

---

### Mobile Platform Files

For iOS (Xcode):
```json
files: {
  "xcode-xcstrings": {
    include: ["Example/Localizable.xcstrings"],
  },
  // Or for traditional .strings files
  "xcode-strings": {
    include: ["Example/[locale].lproj/Localizable.strings"],
  },
}
```

---

For Android:
```json
files: {
  android: {
    include: ["locales/[locale].xml"],
  },
}
```

---

### Other Formats

Here's a complete list of file formats supported by Languine:

- [JSON](/docs/json) - Standard JSON translation files
- [YAML](/docs/yaml) - YAML translation files
- [Properties](/docs/properties) - Java properties files
- [Android](/docs/android) - Android XML resource files
- [iOS](/docs/ios) - iOS localization files
- [iOS Stringsdict](/docs/xcode-stringsdict) - iOS pluralization files
- [iOS XCStrings](/docs/xcode-xcstrings) - Modern Xcode string catalogs
- [Markdown](/docs/md) - Documentation files
- [MDX](/docs/mdx) - Documentation with JSX
- [HTML](/docs/html) - HTML files
- [JavaScript](/docs/js) - JavaScript files
- [TypeScript](/docs/ts) - TypeScript files
- [Gettext PO](/docs/po) - GetText translation files
- [XLIFF](/docs/xliff) - XML Localization Interchange File Format
- [CSV](/docs/csv) - Spreadsheet-based translations
- [XML](/docs/xml) - XML resource files
- [Flutter ARB](/docs/arb) - Application Resource Bundle files
- [PHP](/docs/php) - PHP translation files

---

## File Patterns

The [locale] placeholder in file patterns is automatically replaced with the appropriate language code during translation. For example:

- locales/[locale].json becomes:
  - locales/en.json
  - locales/es.json
  - locales/fr.json

You can include multiple patterns for each file type and use glob patterns:
```json
files: {
  json: {
    include: [
      "src/locales/[locale].json",
      "src/components/[locale]/*.json"
    ],
  },
}
```

---

## Project ID (Optional)

If you're using Languine's cloud services, you can include your project ID in the configuration:

```json
{
  "projectId": "prj_your_project_id",
  "locale": {
    // ... locale config
  },
  files: {
    // ... files config
  },
}
```

---

## Translation State Tracking

Languine automatically creates and maintains a languine.lock file to track the state of your translations. This file:

- Tracks which content has been translated
- Helps identify what needs to be updated when source content changes
- Should be committed to your version control system

You don't need to manually edit the lock file - Languine manages it automatically when you run translation commands.

## Best Practices

1. **Version Control**: Always commit both languine.json and languine.lock to your repository
2. **File Organization**: Keep your translation files organized in a consistent directory structure
3. **Language Codes**: Use standard language codes to ensure compatibility
4. **Patterns**: Use specific include patterns to avoid translating unnecessary files
5. **Project ID**: Keep your project ID secure and don't share it publicly if you're using cloud services, use the `LANGUINE_PROJECT_ID` environment variable instead.
